Release 10.1A: OpenEdge Development:
Java Open Clients

ProDataGraph function and foundations

The ProDataGraph class contains all of the data and schema information required to exchange information with a corresponding ProDataSet or temp-table parameter in an application service. Thus, you can use a ProDataGraph parameter to map any of the following parameter types in the application service:

DATASET — Static ProDataSet parameter.
DATASET-HANDLE — Dynamic ProDataSet parameter.
TABLE — Static temp-table parameter.
TABLE-HANDLE — Dynamic temp-table parameter.

As long as the ProDataGraph is properly prepared, OpenEdge handles all the requirements of passing data between a ProDataGraph parameter and the corresponding application service parameter using these different parameter types. This OpenEdge support also guarantees that Java client programming requirements are mostly identical for both static and dynamic versions of equivalent ProDataSet and temp-table parameters.

Note: The only difference is how the schema can be passed for input static and dynamic parameters. For more information, see the "Passing a ProDataGraph as INPUT or INPUT-OUTPUT" section.

While much of this chapter applies to both individual temp-table and ProDataSet parameters, for more information on passing temp-tables as ProDataGraph parameters, see the "Passing temp-tables as ProDataGraph parameters" section.

Java SDO Foundations

The ProDataGraph class is based on the DataGraph interface specified by the Java Service Data Objects (Java SDO) specification published jointly by BEA and IBM as Java Specification Request (JSR) 235. The OpenEdge class is an extension of the Java SDO reference implementation included as part of the IBM Eclipse Modeling Framework (EMF 2.0.1).

Note: If the work of the JSR 235 Expert Group supersedes the current Java SDO API, the OpenEdge ProDataGraph implementation might have to change in the future.

The Java SDO interface specification consists of several interface objects, including the DataGraph, which closely model the 4GL ProDataSet. Like the ProDataSet, it provides:

Relationship support.
A detached data source.
XML serialization.
Data introspection (meta data or schema support).
Change tracking.

The DataObject is the fundamental interface of Java SDO and is the Java SDO representation of structured data. It encapsulates a specified set of properties (Property objects). Each property has a Type object, which can specify one of the following data types:

A primitive or derived type, such as int (primitive) or Date (derived), typically representative of a column property.
A reference type, which refers to the type of another DataObject, and is representative of a reference property.

Each DataObject provides read and write access methods for all its properties. (For more information on using the Java SDO Property and Type interfaces, see the "Using Java SDO classes to access Property meta data" section.)

A DataGraph encapsulates a tree of DataObject instances starting with a single root DataObject. The reference properties of each DataObject link to other DataObject instances in the tree. In a DataGraph of relational data, a DataObject commonly represents a row of data, where its column properties represent the data fields of the row and its reference properties link to ordered or otherwise related rows. Foreign keys are represented by references to DataObject instances representing a row or rows in another table. Thus, reference properties can maintain relationships between parent and child tables. The rows of a single table are represented by a DataObject list (java.util.List).

The Property and Type interfaces that define data fields in a table row represented by a DataObject also provide the Java SDO meta data API. This API provides access to the DataObject schema, allowing the client to introspect the DataObject to get its type information.

Thus, the whole character of a DataGraph depends on the specific definitions of the DataObject instances in its tree. While this tree seems to imply a hierarchical structure, it can be used to model many other complex data structures, depending on how its DataObject instances are defined and interrelated. In order to more closely map a ProDataSet, the OpenEdge ProDataGraph represents a constraint on the standard DataGraph. A ProDataGraph encapsulates a tree of ProDataObject instances, starting with a specially-defined root DataObject, which essentially references the tables (ProDataObject lists) contained by the ProDataGraph and its corresponding ProDataSet. (For more information on this tree structure, see the "ProDataGraph object model" section.)

A DataGraph also encapsulates a ChangeSummary object whose interface tracks changes to any of its underlying DataObject instances. The ChangeSummary object is initially empty and populated as the DataGraph is modified. This ChangeSummary allows Java SDO to apply changes back to the data source of a DataGraph by comparing changed properties and DataObject instances with the current state of the data source. The ProDataGraph class encapsulates a corresponding ProChangeSummary object, which extends the ChangeSummary interface to more closely model the operation of the corresponding ProDataSet.

Java SDO also provides components called Data Mediator Services, which provide access to heterogeneous data sources for a DataGraph. They enable the DataGraph to function independently of any one data source so it can serve as a common unit of transfer for data throughout an application. The OpenEdge ProDataGraph does not require Data Mediator Services, as the data source for a ProDataGraph (and its corresponding ProDataSet) is typically managed by the OpenEdge application service.

For more information on:

Documentation for the Service Data Objects in EMF 2.0.1, see http://eclipse.org/emf/docs.php.
JSR 235, see http://www.jcp.org/en/jsr/detail?id=235.

Java SDO extensions

While Java SDO closely models the capabilities of the Progress 4GL ProDataSet, the ProDataGraph extensions provide additional support to address the following Java SDO limitations:

Java SDO provides a minimal meta data API that allows clients to introspect data in a DataGraph. However, to more easily define and access the meta data of a ProDataGraph, OpenEdge provides its own classes, ProDataGraphMetaData and ProDataObjectMetaData, to store the schema for a ProDataGraph.
Java SDO provides relationship support by allowing a DataObject (table row) to contain references to other DataObject instances (representing rows in another table). However, it provides no means to describe these relationships as provided for ProDataSets. There is no meta data that describes the field names in the parent and child tables that form the primary-foreign key relationships. OpenEdge provides its own ProDataRelationMetaData class to describe each entity relation (data-relation) in a ProDataGraph.
Java SDO does not support the java.util.GregorianCalendar class as a data type for DataObject fields. This data type is essential to map ProDataSet fields that have the DATETIME or DATETIME-TZ data type. The OpenEdge ProDataObject class supports the java.util.GregorianCalendar class as a data type for ProDataObject fields.
Note: Java SDO supports the java.util.Date class, but many of its methods are deprecated as of JDK 1.1 because they are not suitable for internationalization.
The Java SDO ChangeSummary object that tracks changes to any DataObject rows in a DataGraph returns these changes as a list of DataObject rows. However, to efficiently marshall these updates back to the AppServer, these changed rows must be returned to the AppServer as a changes-only ProDataGraph, which maps to a changes-only ProDataSet in the application service. The OpenEdge ProChangeSummary class tracks all ProDataObject changes and returns them in a changes-only ProDataGraph.

Table 5–1 summarizes all the OpenEdge classes that support the ProDataGraph extension to Java SDO. They all reside in the com.progress.open4gl package. For more information on how these objects work together, in a typical ProDataGraph, see the "ProDataGraph object model" section.

Table 5–1: OpenEdge classes that extend Java SDO

OpenEdge class	Basis	For more information, see...
ProDataGraph	Extends DataGraph to map ProDataSets.	"ProDataGraph class" section.
ProDataObject	Extends DataObject to support java.util.GregorianCalendar and provide relational navigation among tables.	"ProDataObject class" section.
ProChangeSummary	Extends ChangeSummary to return all ProDataObject changes in a changes-only ProDataGraph.	"ProChangeSummary class" section.
ProDataGraphMetaData	OpenEdge-based class to more easily manage ProDataGraph schema information.	"ProDataGraphMetaData class" section.
ProDataObjectMetaData	OpenEdge-based class to more easily manage ProDataObject schema information.	"ProDataObjectMetaData class" section.
ProDataRelationMetaData	OpenEdge-based class to describe ProDataGraph data-relations.	"ProDataRelationMetaData class" section.